Enterprise Objects Framework Release 1.1 Copyright ã1995 by NeXT Computer, Inc.  All Rights Reserved.

EODatabaseDataSource

Inherits From:	NSObject

Conforms To:	EODataSources (through EOMasterDataSources)
EOMasterDataSources
EOQualifiableDataSources
EORollbackDataSources

Declared In:	eoaccess/EODatabaseDataSource.h

Class Description

An EODatabaseDataSource is a data source (as described in the EODataSources protocol specification) that manages objects created from data in a relational database. It supports all of the data sources protocols, and adds methods for specifying qualifiers to select objects and for determining the order in which they're fetched. An EODatabaseDataSource can serve as either a master or a peer data source (see the EOQualifiableDataSources protocol specification for information on these kinds of data sources).

An EODatabaseDataSource uses two qualifiers for fetching its objects: a primary qualifier, which is required, and an auxiliary qualifier, which is optional and can be used to further restrict the set of objects the data source fetches. The data source conjoins the two qualifiers when it performs a fetch. In addition to the two qualifiers, an EODatabaseDataSource accepts a fetch ordering specification so that it can sort objects when fetching them.

For EODatabaseDataSource, a saveObjects message commits the last transaction that the data source started. EODatabaseDataSource also implements the rollback method of the EORollbackDataSources protocol, but doesn't implement a method to explicitly begin transactions. Instead, it automatically begins transactions as needed whenever an insertion, deletion, update, or fetch operation is performed. You can disable this behavior with a setBeginsTransactionsAutomatically: message, but then you have to get the data source's EODatabaseContext and use it to begin transactions.

Rendezvous on Database-level objects

An EODatabaseDataSource can be initialized in such a way that it will share existing database-level objects with other EODatabaseDataSources. initWithModelName:entityName:databaseName:databaseContextName:databaseChannelName: takes three arguments naming an EODatabase, an EODatabaseContext, and an EODatabaseChannel. It looks up each name in an internal table, global to your application: If it finds an object registered under the name, it uses that object, otherwise it creates a new one and registers it under the given name. This mechanism is typically used for EODatabaseDataSources created from EOControllers in nib files.

The names are looked up in order for the EODatabase, then the EODatabaseContext belonging to the EODatabase, and finally the EODatabaseChannel belonging to the EODatabaseContext. This results in a natural scoping of names, so that, for example, two different EODatabase objects can each have an EODatabaseContext registered under the same name.

Note:  Empty strings (and equivalently, nil) are considered names, so you can't guarantee that a database data source will have its own database-level objects by specifying these as names. You're responsible for knowing which names have been used and specifying new ones if you want a new database data source to have its own database-level objects.

Instance Variables

None declared in this class.

Adopted Protocols

EODataSources	- keys
- coerceValue:forKey:
- fetchObjects
- saveObjects
- createObject
- insertObject:
- canDelete
- deleteObject:
- updateObject:

EOMasterDataSources	- dataSourceQualifiedByKey:

EOQualifiableDataSources	- qualifyWithRelationshipKey:ofObject:

EORollbackDataSources	- rollback

Method Types

Initializing instances	- initWithDatabaseChannel:entityNamed:
- initWithModelName:entityName:
- initWithModelName:entityName:databaseName:
contextName:channelName:

Naming a database channel	+ registerChannel:forRendezvousWithDatabaseName:
	       contextName:channelName:

Getting the database channel	- databaseChannel
+ databaseChannelWithDatabaseName:contextName:
 channelName:

Releasing a database channel	+ releaseObjectsWithDatabaseName:contextName:
       channelName:

Getting the root entity	- entity

Setting automatic transaction control
- setBeginsTransactionsAutomatically:
- beginsTransactionsAutomatically

Setting the qualifier	- setQualifier:
- qualifier
- setAuxiliaryQualifier:
- auxiliaryQualifier
- qualifierForFetch:

Enabling fetching	- setFetchEnabled:
- isFetchEnabled

Setting the fetch order	- setFetchOrder:
- fetchOrder

Class Methods

databaseChannelWithDatabaseName:contextName:channelName:

+ (EODatabaseChannel *)databaseChannelWithDatabaseName:(NSString *)aDatabaseName contextName:(NSString *)aContextName channelName:(NSString *)aChannelName

Returns the database channel registered under the specified database, context, and channel names.

See also:  + registerChannel:forRendezvousWithDatabaseName:contextName:channelName:, + releaseObjectsWithDatabaseName:contextName:channelName:

registerChannel:forRendezvousWithDatabaseName:contextName:channelName:

+ (void)registerChannel:(EODatabaseChannel *)channel forRendezvousWithDatabaseName:(NSString *)aDatabaseName contextName:(NSString *)aContextName 
channelName:(NSString *)aChannelName

Registers the channel and its parent context and database in the EODatabaseDataSource rendezvous dictionary. If a component is already registered under the specified name, it is replaced with the new component. A counter is associated with each named component: Each time registerChannel:forRendezvousWithDatabaseName:contextName:channelName or an init method is invoked, the counter associated with each of the names used by that method is incremented. When an EODatabaseDataSource is dealloc'ed, it decrements the counters associated with any components that it rendezvoused with at init time. 

See also:  + databaseChannelWithDatabaseName:contextName:channelName:, + releaseObjectsWithDatabaseName:contextName:channelName:

releaseObjectsWithDatabaseName:contextName:channelName:

+ (void)releaseObjectsWithDatabaseName:(NSString *)aDatabaseName contextName:(NSString *)aContextName 
channelName:(NSString *)aChannelName

Decrements the counters associated with each of its name arguments. When a counter reaches 0, its associated name and object are removed from the rendezvous dictionary.

See also:  + databaseChannelWithDatabaseName:contextName:channelName:, + registerChannel:forRendezvousWithDatabaseName:contextName:channelName:

Instance Methods

auxiliaryQualifier

- (EOQualifier *)auxiliaryQualifier

Returns the auxiliary qualifier used with the primary qualifier when fetching objects. This qualifier usually adds conditions to the primary qualifier and is useful for narrowing the scope of a data source without altering its primary qualifier. This is especially useful for setting a qualifier on a qualified peer data source, since the master sets the peer's primary qualifier to specify the relationship it fetches for.

See also:  - auxiliaryQualifier, - qualifierForFetch, - qualifier (EOEntity)

beginsTransactionsAutomatically

- (BOOL)beginsTransactionsAutomatically

Returns YES if the data source automatically starts a transaction if needed upon the first insert, delete, or update; returns NO if it doesn't. If this method returns NO you must control transactions explicitly through the data source's EODatabaseContext. EODatabaseDataSources by default do begin transactions automatically.

canDelete

@protocol EODataSources
- (BOOL)canDelete

Returns NO if the data source's entity is read-only, YES otherwise.

See also:  - isReadOnly (EOEntity)

coerceValue:forKey:

@protocol EODataSources
- coerceValue:aValue forKey:(NSString *)key

Returns aValue as an instance of the value class defined for the attribute named key of the receiver's entity. Returns nil if aValue couldn't be coerced to the new type. Returns aValue passed in if the key does not correspond to an attribute.

For example, suppose the Employee entity has an attribute named dateHired with a value class of NSCalendarDate. If you send coerceValue:forKey: to a database data source with an NSString as the value and ªdateHiredº as the key, it creates an NSCalendarDate from the string value and returns it.

See also:  - entity, - valueClassName (EOAttribute)

createObject

@protocol EODataSources
- createObject

Returns a new enterprise object with no values set, allocated from the data source's zone and initialized as described below, or nil if the receiver's EOEntity is read-only. The sender of this message is responsible for setting the enterprise object's property values (especially its primary key) and for then inserting the newly created object into the data source.

If the new enterprise object responds to initWithPrimaryKey:entity: it's initialized with that method, with nil as the primary key and with the data source's entity. If the enterprise object doesn't respond to initWithPrimaryKey:entity:, it's initialized with init.

databaseChannel

- (EODatabaseChannel *)databaseChannel

Returns the EODatabaseChannel that the data source uses to communicate with the database server. You can use this channel to control transactions if you've disabled automatic transactions with the setBeginsTransactionsAutomatically: method, but should be careful about altering other state, as it can cause errors in the database data source.

dataSourceQualifiedByKey:

@protocol EOMasterDataSources
- (id <EOQualifiableDataSources>)dataSourceQualifiedByKey:(NSString *)relName

Returns an EODetailDatabaseDataSource object that provides objects for the destination of the relationship named relName of the receiver's entity. Before using the detail data source you have to give it a master object with qualifyWithRelationshipKey:ofObject:.

Returns nil if the entity has no relationship named relName or if that relationship has no destination entity.

See also:  - entity

deleteObject:

@protocol EODataSources
- (BOOL)deleteObject:anEO

Sends deleteObject: to the receiver's database channel with anEO as the argument. Returns YES on success, NO on failure.

See also:  - canDelete (EODataSources protocol)

entity

- (EOEntity *)entity

Returns the entity that the EODatabaseDataSource fetches objects for. This is the entity of the EODatabaseDataSource's qualifier.

See also:  - qualifier

fetchObjects

@protocol EODataSources
- (NSArray *)fetchObjects

Returns the data source's objects, issuing a fetch to the underlying database to retrieve them. This set of objects includes those that have been inserted but not saved. Returns nil if fetching is disabled or an error occurs.

See also:  - isFetchEnabled, - qualifierForFetch, - fetchOrder

fetchOrder

- (NSArray *)fetchOrder

Returns the fetch order used when supplying objects. See the EOAttributeOrdering class specification for more information.

initWithDatabaseChannel:entityNamed: 

- initWithDatabaseChannel:(EODatabaseChannel *)aChannel
entityNamed:(NSString *)entityName

Initializes a newly allocated EODatabaseDataSource with aChannel as its communication channel to the database, and with the entity in aChannel's model named entityName as its root entity. Doesn't use the rendezvous mechanism of initWithModelName:entityName:databaseName:contextName:channelName:. This is the designated initializer for the EODatabaseDataSource class. Returns self.

initWithModelName:entityName: 

- initWithModelName:(NSString *)modelName
entityName:(NSString *)entityName

Initializes a newly allocated EODatabaseDataSource with the model named modelName and with the entity named entityName as its root entity. Invoking this method is equivalent to invoking initWithModelName:entityName:databaseName:contextName:channelName: with the model's name, the entity's name, and with nil for all database component rendezvous names. Returns self.

See also:  + findPathForModelNamed: (EOModel)

initWithModelName:entityName:databaseName:contextName:
channelName: 

- initWithModelName:(NSString *)modelName
entityName:(NSString *)entityName
databaseName:(NSString *)databaseName
contextName:(NSString *)contextName
channelName:(NSString *)channelName

Initializes a newly allocated EODatabaseDataSource with the model named modelName and with the entity named entityName as its root entity. Returns self.

This method uses the last three name arguments to share database-level objects with other instances, as described in the class description under ªRendezvous on Database-level objects.º

See also:  + findPathForModelNamed: (EOModel)

insertObject:

@protocol EODataSources
- (BOOL)insertObject:anEO

Sends insertObject: to the receiver's database channel with anEO as the argument. anEO must have a unique, valid primary key. Returns YES on success, NO on failure.

isFetchEnabled

- (BOOL)isFetchEnabled

Returns YES if fetchObjects is enabled, NO if it fetchObjects returns no objects instead of fetching (as, for example, when a detail controller's master has no object selected).

qualifier

- (EOQualifier *)qualifier

Returns the primary qualifier used when fetching objects. This qualifier minimally specifies the EODatabaseDataSource's entity, and may contain more restrictive information. It's set by the qualifyWithRelationshipKey:ofObject: method declared in the EOQualifiableDataSources protocol.

See also:  - auxiliaryQualifier, - qualifierForFetch, - qualifier (EOEntity)

qualifierForFetch

- (EOQualifier *)qualifierForFetch

Returns the qualifier used when fetching objects. This qualifier is the conjunction of the primary qualifier and the auxiliary qualifier.

See also:  - auxiliaryQualifier, - qualifier, - conjoinWithQualifier: (EOQualifier)

qualifyWithRelationshipKey:ofObject:

@protocol EOQualifiableDataSources
- (void)qualifyWithRelationshipKey:(NSString *)relName
ofObject:anEO

Qualifies the receiver so that it supplies objects based on relName, which is the name of an EORelationship of the EOEntity for anEO. This results in the receiver's entity and primary qualifier being changed.

If anEO is nil, the detail data source disables fetching by invoking setFetchEnabled:; this is useful for temporarily ªturning offº a qualified peer data source when no records are selected in its master.

rollback

@protocol EORollbackDataSources
- (void)rollback

If the receiver automatically started the current transaction, sends rollbackTransaction to the database context of the receiver's database channel. Doesn't affect the data source's enterprise objects. Returns YES on success, NO on failure.

saveObjects

@protocol EODataSources
- (BOOL)saveObjects

If the receiver automatically started the current transaction, sends commitTransaction to the database context of the receiver's database channel. Returns YES on success, NO on failure.

setAuxiliaryQualifier:

- (void)setAuxiliaryQualifier:(EOQualifier *)aQualifier

Sets to aQualifier the auxiliary qualifier used with the primary qualifier when fetching objects. This qualifier usually adds conditions to the primary qualifier and is useful for narrowing the scope of a data source without altering its primary qualifier.

Raises NSInvalidArgumentException if aQualifier's entity isn't the same as the primary qualifier's.

See also:  - auxiliaryQualifier, - qualifierForFetch

setBeginsTransactionsAutomatically:

- (void)setBeginsTransactionsAutomatically:(BOOL)flag

Sets whether the data source automatically starts a transaction if needed upon the first insert, delete, or update, according to flag. If you turn this behavior off then you must control transactions explicitly through the data source's EODatabaseChannel. This behavior is enabled by default.

See also:  - databaseChannel

setFetchEnabled:

- (void)setFetchEnabled:(BOOL)flag

Enables fetching according to flag. If flag is NO, then fetchObjects returns no objects until fetching is enabled again.

setFetchOrder:

- (void)setFetchOrder:(NSArray *)fetchOrder

Sets to fetchOrder the fetch order used for retrieving objects from the database. See the EOAttributeOrdering class specification for more information.

setQualifier:

- (void)setQualifier:(EOQualifier *)aQualifier

Sets to aQualifier the primary qualifier used with the auxiliary qualifier when fetching objects. This qualifier minimally specifies the EODatabaseDataSource's entity, and may contain more restrictive information (though that's typically put in the auxiliary qualifier). You must supply a valid qualifier to this method; if aQualifier is nil, subsequent fetches will not retrive objects from the database.

This method is invoked by qualifyWithRelationshipKey:ofObject: when an EODatabaseDataSource is set up as a qualified peer.

See also:  - setAuxiliaryQualifier:, - qualifierForFetch, - qualifier (EOEntity)

updateObject:

@protocol EODataSources
- (BOOL)updateObject:anEO

Sends updateObject: to the receiver's database channel with anEO as the argument. Returns YES on success, NO on failure.